home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / perl5 / CGI::Carp.z / CGI::Carp
Encoding:
Text File  |  2002-10-03  |  8.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp - CGI routines for writing to the HTTPD (or other) error log
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.          use CGI::Carp;
  13.  
  14.          croak "We're outta here!";
  15.          confess "It was my fault: $!";
  16.          carp "It was your fault!";
  17.          warn "I'm confused";
  18.          die  "I'm dying.\n";
  19.  
  20.  
  21. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.      CGI scripts have a nasty habit of leaving warning messages in the error
  23.      logs that are neither time stamped nor fully identified.  Tracking down
  24.      the script that caused the error is a pain.  This fixes that.  Replace
  25.      the usual
  26.  
  27.          use Carp;
  28.  
  29.      with
  30.  
  31.          use CGI::Carp
  32.  
  33.      And the standard _w_a_r_n(), die (), _c_r_o_a_k(), _c_o_n_f_e_s_s() and _c_a_r_p() calls will
  34.      automagically be replaced with functions that write out nicely time-
  35.      stamped messages to the HTTP server error log.
  36.  
  37.      For example:
  38.  
  39.         [Fri Nov 17 21:40:43 1995] test.pl: I'm confused at test.pl line 3.
  40.         [Fri Nov 17 21:40:43 1995] test.pl: Got an error message: Permission denied.
  41.         [Fri Nov 17 21:40:43 1995] test.pl: I'm dying.
  42.  
  43.  
  44. RRRREEEEDDDDIIIIRRRREEEECCCCTTTTIIIINNNNGGGG EEEERRRRRRRROOOORRRR MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS
  45.      By default, error messages are sent to STDERR.  Most HTTPD servers direct
  46.      STDERR to the server's error log.  Some applications may wish to keep
  47.      private error logs, distinct from the server's error log, or they may
  48.      wish to direct error messages to STDOUT so that the browser will receive
  49.      them.
  50.  
  51.      The carpout() function is provided for this purpose.  Since _c_a_r_p_o_u_t() is
  52.      not exported by default, you must import it explicitly by saying
  53.  
  54.         use CGI::Carp qw(carpout);
  55.  
  56.      The _c_a_r_p_o_u_t() function requires one argument, which should be a reference
  57.      to an open filehandle for writing errors.  It should be called in a BEGIN
  58.      block at the top of the CGI application so that compiler errors will be
  59.      caught.  Example:
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  71.  
  72.  
  73.  
  74.         BEGIN {
  75.           use CGI::Carp qw(carpout);
  76.           open(LOG, ">>/usr/local/cgi-logs/mycgi-log") or
  77.             die("Unable to open mycgi-log: $!\n");
  78.           carpout(LOG);
  79.         }
  80.  
  81.      _c_a_r_p_o_u_t() does not handle file locking on the log for you at this point.
  82.  
  83.      The real STDERR is not closed -- it is moved to SAVEERR.  Some servers,
  84.      when dealing with CGI scripts, close their connection to the browser when
  85.      the script closes STDOUT and STDERR.  SAVEERR is used to prevent this
  86.      from happening prematurely.
  87.  
  88.      You can pass filehandles to _c_a_r_p_o_u_t() in a variety of ways.  The
  89.      "correct" way according to Tom Christiansen is to pass a reference to a
  90.      filehandle GLOB:
  91.  
  92.          carpout(\*LOG);
  93.  
  94.      This looks weird to mere mortals however, so the following syntaxes are
  95.      accepted as well:
  96.  
  97.          carpout(LOG);
  98.          carpout(main::LOG);
  99.          carpout(main'LOG);
  100.          carpout(\LOG);
  101.          carpout(\'main::LOG');
  102.  
  103.          ... and so on
  104.  
  105.      FileHandle and other objects work as well.
  106.  
  107.      Use of _c_a_r_p_o_u_t() is not great for performance, so it is recommended for
  108.      debugging purposes or for moderate-use applications.  A future version of
  109.      this module may delay redirecting STDERR until one of the CGI::Carp
  110.      methods is called to prevent the performance hit.
  111.  
  112. MMMMAAAAKKKKIIIINNNNGGGG PPPPEEEERRRRLLLL EEEERRRRRRRROOOORRRRSSSS AAAAPPPPPPPPEEEEAAAARRRR IIIINNNN TTTTHHHHEEEE BBBBRRRROOOOWWWWSSSSEEEERRRR WWWWIIIINNNNDDDDOOOOWWWW
  113.      If you want to send fatal (die, confess) errors to the browser, ask to
  114.      import the special "fatalsToBrowser" subroutine:
  115.  
  116.          use CGI::Carp qw(fatalsToBrowser);
  117.          die "Bad error here";
  118.  
  119.      Fatal errors will now be echoed to the browser as well as to the log.
  120.      CGI::Carp arranges to send a minimal HTTP header to the browser so that
  121.      even errors that occur in the early compile phase will be seen.  Nonfatal
  122.      errors will still be directed to the log file only (unless redirected
  123.      with carpout).
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  137.  
  138.  
  139.  
  140.      CCCChhhhaaaannnnggggiiiinnnngggg tttthhhheeee ddddeeeeffffaaaauuuulllltttt mmmmeeeessssssssaaaaggggeeee
  141.  
  142.      By default, the software error message is followed by a note to contact
  143.      the Webmaster by e-mail with the time and date of the error.  If this
  144.      message is not to your liking, you can change it using the _s_e_t__m_e_s_s_a_g_e()
  145.      routine.  This is not imported by default; you should import it on the
  146.      _u_s_e() line:
  147.  
  148.          use CGI::Carp qw(fatalsToBrowser set_message);
  149.          set_message("It's not a bug, it's a feature!");
  150.  
  151.      You may also pass in a code reference in order to create a custom error
  152.      message.  At run time, your code will be called with the text of the
  153.      error message that caused the script to die.  Example:
  154.  
  155.          use CGI::Carp qw(fatalsToBrowser set_message);
  156.          BEGIN {
  157.             sub handle_errors {
  158.                my $msg = shift;
  159.                print "<h1>Oh gosh</h1>";
  160.                print "Got an error: $msg";
  161.            }
  162.            set_message(\&handle_errors);
  163.          }
  164.  
  165.      In order to correctly intercept compile-time errors, you should call
  166.      _s_e_t__m_e_s_s_a_g_e() from within a BEGIN{} block.
  167.  
  168. CCCCHHHHAAAANNNNGGGGEEEE LLLLOOOOGGGG
  169.      1.05 _c_a_r_p_o_u_t() added and minor corrections by Marc Hedlund
  170.           <hedlund@best.com> on 11/26/95.
  171.  
  172.      1.06 _f_a_t_a_l_s_T_o_B_r_o_w_s_e_r() no longer aborts for fatal errors within
  173.           _e_v_a_l() statements.
  174.  
  175.      1.08 _s_e_t__m_e_s_s_a_g_e() added and _c_a_r_p_o_u_t() expanded to allow for FileHandle
  176.           objects.
  177.  
  178.      1.09 _s_e_t__m_e_s_s_a_g_e() now allows users to pass a code REFERENCE for
  179.           really custom error messages.  croak and carp are now
  180.           exported by default.  Thanks to Gunther Birznieks for the
  181.           patches.
  182.  
  183.      1.10 Patch from Chris Dean (ctdean@cogit.com) to allow
  184.           module to run correctly under mod_perl.
  185.  
  186. AAAAUUUUTTTTHHHHOOOORRRRSSSS
  187.      Lincoln D. Stein <lstein@genome.wi.mit.edu>.  Feel free to redistribute
  188.      this under the Perl Artistic License.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  203.  
  204.  
  205.  
  206. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  207.      Carp, CGI::Base, CGI::BasePlus, CGI::Request, CGI::MiniSvr, CGI::Form,
  208.      CGI::Response
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.